home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / comm.com / COMM.DOC < prev    next >
Encoding:
Text File  |  1988-09-22  |  7.2 KB  |  307 lines
  1.  
  2. Docs for COMM.H C communications header file by 
  3.  
  4. Mario Giannini - Compuserve ID: 76276,1576
  5. New York, New York
  6.  
  7. Notes:
  8.  
  9.   BUFSIZE is the size of the communications buffer, the default is 8K.
  10.           To change this ad the following line to your main source file:
  11.  
  12.   # define BUFSIZE xxxxx
  13.           Where xxxxx is the size of the buffer in bytes.
  14.  
  15.  
  16.   port - When a port number is required, a 0 specifies COM1 and 1 specifies
  17.          COM2.
  18.  
  19. Commands:
  20.  
  21. The folowing functions are defined in COMM.H and can be called once they
  22. have been combined with your source file using the following line, note that
  23. functions that do not specify a COM port will use the port for the last
  24. succesful setintr function.
  25.  
  26. #include <comm.h>
  27.  
  28. ------------------------------------------------------------------------
  29. setintr
  30.  
  31.    summary:
  32.  
  33.    #include <comm.h>
  34.  
  35.    int setintr(port);
  36.    int port;            COM port on PC
  37.  
  38.    description:
  39.  
  40.    The setintr function installs the communications interrupt handler for
  41.    the specified COM port.  The port is deteremined by the following 
  42.    variables:
  43.  
  44.       port      COM?:
  45.       ====      ===== 
  46.         0       COM1:
  47.         1       COM2:
  48.  
  49.  
  50.   Returns Value:
  51.  
  52.   setintr returns a 0 if successful, or a -1 if the specified port was
  53.   not found.
  54.  
  55.  
  56.   example:
  57.  
  58.   if (setintr(0))
  59.      printf("Unable to set interrupt\n");
  60.  
  61. ------------------------------------------------------------------------
  62. resetint
  63.  
  64.    summary:
  65.  
  66.    void resetint(port);
  67.    int port;                 COM port on PC
  68.  
  69.    description:
  70.  
  71.    The resetint function will remove the interrupt handler associated with
  72.    the com port specified by port.  Care must be taken not to call this
  73.    function if setintr() was not succesful, this might cause the machine
  74.    to lock up under other communications systems.
  75.  
  76.    Return Value:
  77.  
  78.    resetint does not return a value.   
  79.  
  80.    example:
  81.   
  82.    resetint(0);
  83. ------------------------------------------------------------------------
  84. seravl
  85.  
  86.    summary:
  87.  
  88.    int seravl();
  89.  
  90.    The seravl function resturns a non-zero if there is a character in the
  91.    communications buffer.  This function should be called before calling
  92.    the getser function to avoid the buffer table pointers from collision
  93.    (resulting in 1 buffer full of garbage data.
  94.  
  95.    Return Value:
  96.  
  97.    seravl returns a non-zero if a character is available in the com buffer,
  98.    or a zero if not.
  99.  
  100.    example:
  101.  
  102.    if (seravl())
  103.       printf("A character is in the buffer\n");
  104. ------------------------------------------------------------------------
  105. getser
  106.  
  107.    summary:
  108.    #include <comm.h>
  109.  
  110.    int getser();
  111.  
  112.    description:
  113.  
  114.    The getser function will get a character from the serial buffer.  Make
  115.    sure to check that a character is avaiable with the seravl() function
  116.    before getting it.
  117.  
  118.    Return Value:
  119.  
  120.    getser returns the ASCII value of the next character to be read from the
  121.    com buffer
  122.  
  123.    example:
  124.  
  125.    int ch;
  126.  
  127.    if (seravl())
  128.    {
  129.        ch=getser();
  130.        printf("Character received: %c\n", ch);
  131.    }
  132. ------------------------------------------------------------------------
  133. portinit
  134.  
  135.   summary:
  136.   #include <comm.h>
  137.  
  138.   int portinit(port, baud, parity, data, stop);
  139.   int port;    com port to initialize
  140.   int baud;    baud rate (tested upto 9600)
  141.   int parity;  parity: (0=none, 1=odd, 2=even)
  142.   int data;    data bits (6-8)
  143.   int stop;    stop bits (0-2)
  144.  
  145.   description:
  146.  
  147.   The portinit set the UART chip connect to the COM port specified
  148.   by port to the above mentioned parameters.
  149.  
  150.   return value:
  151.            returns  0 if ok                      
  152.                    -1 if port not there,         
  153.                    -2 if invalid parameter
  154.  
  155.    example:
  156.   
  157.    if (portinit(0, 1200, 0, 8, 1))
  158.       printf("Error initialising COMM port\n");
  159. ------------------------------------------------------------------------
  160. is_carrier
  161.  
  162.   summary:
  163.  
  164.   #include <comm.h>
  165.  
  166.   int is_carrier(port);
  167.  
  168.   int port;     com port to check for carrier
  169.  
  170.   description:
  171.  
  172.   The is_carrier function returns a zero if there is no Carrier Detect (CD)
  173.   signal detected at the specified com port, a non-zero otherwise.
  174.  
  175.   example:
  176.  
  177.   if (is_carrier(0))
  178.      printf("Carrier detected at COM1:\n");
  179. ------------------------------------------------------------------------
  180. sendstr
  181.  
  182.   summary:
  183.  
  184.   #include <comm.h>
  185.  
  186.   void sendstr(str)
  187.  
  188.   char *str;    string to be sent to modem.
  189.  
  190.   description:
  191.  
  192.    The sendstr function allows NULL-terminated strings to be sent to the
  193.    modem.  The following characters have a special meaning to sendstr when
  194.    used in the string being sent:
  195.  
  196.       |  This character is replaced with a carriage return
  197.  
  198.       ~  This character causes the string to wait 1 second before
  199.          continuing to send the rest of the string.  Note:  This
  200.          function does not work the same way as the comma in the
  201.          Hayes ATDT command which sends the string and pauses the
  202.          function (dialing) for 2 seconds.
  203.  
  204.  
  205.    Return Value:
  206.  
  207.    sendstr has no return value.
  208.  
  209.    exmaple:
  210.  
  211.    sendstr("||~+++~|ATH|");
  212.  
  213.    The above example will send two CR's to the modem, then wait one
  214.    one second, it will then send a +++, and wait again for 1 second.
  215.    Once that wait is over it sends a CR, ATH, and another CR.  This
  216.    sequence will usually work as a software hangup method.
  217. ------------------------------------------------------------------------
  218. xmit
  219.  
  220.    summary:
  221.    
  222.    void xmit(ch);
  223.  
  224.   int ch;     character to send to COM port.
  225.  
  226.   description:
  227.  
  228.   the xmit function will transmit one character specified by ch out the
  229.   serail port last used by the setintr function.
  230.  
  231.   Return Value:
  232.  
  233.   xmit has no return value.
  234.  
  235. ------------------------------------------------------------------------
  236. clr_buf
  237.  
  238.  
  239.   summary:
  240.  
  241.   void clr_buf();
  242.  
  243.   description:
  244.  
  245.   clr_buff clears out all character in the communications buffer.
  246.  
  247.   Return Value:
  248.  
  249.   clr_buf has no return value.
  250.  
  251.   example:
  252.  
  253.   clr_buf();
  254.  
  255.   The buffer was just wiped clear.
  256. ------------------------------------------------------------------------
  257. onesec
  258.  
  259.   summary:
  260.  
  261.   #include <comm.h>
  262.  
  263.   void onesec();
  264.  
  265.   description:
  266.  
  267.   This function when called will create a one second time delay.  It used
  268.   by the snedstr function and may also prove useful for certain timed file
  269.   transfer protocols.
  270.  
  271.    Return Value:
  272.  
  273.    onesec has no return value.
  274.  
  275.   example:
  276.  
  277.   printf("Please wait one second...");
  278.   onesec();
  279.   printf("Thank you\n");
  280. ------------------------------------------------------------------------
  281. hwhangup
  282.  
  283.   summary:
  284.  
  285.   #include <comm.h>
  286.  
  287.   void hwhangup();
  288.  
  289.   description:
  290.  
  291.   The function inverts the signal from the DTR signal out of the COM port
  292.   to perform a hardware hangup for modems that support it.
  293.  
  294.   Return Value:
  295.  
  296.   hwhangup has no return value.
  297.  
  298.   example:
  299.  
  300.   sendstr("Disconnecting from system...");
  301.   hwhangup();
  302.  
  303.   The above example would send the string "Disconnecting from system..." to
  304.   the modem (and through to any users connect) and the hangup the modem
  305.   via the DTR technique.
  306. ------------------------------------------------------------------------
  307.